Optimize MiniMax Music 3 inference on Apple Silicon - #294

What changed

• optimize the native MiniMax Music 3 BF16 graph with a reachable 16,385-row semantic head, fused QKV and gate/up projections, incremental residual-depth KV caches, cached rotary and zero conditioning, batched flow CFG, and fewer forced evaluations
• add explicit reference, optimized, q8, and q4 performance modes; optimized BF16 remains the default and Q8/Q4 quantize only the autoregressive language/depth stack
• add strict --minimum-duration / --min-frames controls plus matching speech API fields and schema-3 recipe metadata
• correct second-based duration floors for whole 512-sample vocoder hops
• document the controls, benchmark method, rejected experiments, and measured physical limit

Why

The released graph preserved upstream behavior but left substantial Apple Silicon performance unused:

• the 25 Hz sampler projected a 200,000-token vocabulary even though only EOS plus 16,384 semantic codes are reachable
• attention and feed-forward projections launched separately
• residual depth decoding recomputed the full prefix for each codebook
• flow CFG repeated serial conditional/unconditional passes and rebuilt invariant tensors
• duration * 25 could decode slightly short because the vocoder emits whole hops

The reference path retains the released operation ordering for exact recovery and A/B work.

Measured impact

Matched 250-frame, 30-step staged runs on an M4 Max:

Installed-checkpoint semantic-logit gates:

• Q8: cosine 0.9998546, top-100 overlap 98/100
• Q4: cosine 0.9916618, top-100 overlap 80/100

A strict 180-second Q8 render completed in 1,413.81 seconds, used 4.50 GB maximum resident memory, and decoded to 180.268 seconds. A strict 60-second render decoded to 60.105 seconds.

The finished reference path produced a byte-identical 250-frame PCM24 render against clean 0.37.0: SHA-256 6aee35f704ae5621f3bbc9b4b2ec04080931f8ec4a7db1e9099cf4ac4aaf5890.

Whole-flow compilation, flow-weight quantization, and serial CFG were benchmarked and rejected because they regressed end-to-end performance. Flow therefore remains BF16.

Validation

• ./scripts/check.sh after rebasing onto current origin/main
• 2,823 XCTest cases: 0 failures, 206 checkpoint-gated skips
• 28 Swift Testing cases: passed
• strict SwiftLint, build, CLI help sweep, and hygiene scans: passed
• release mere.run product build: passed
• installed-checkpoint Q8/Q4 quality gate on Metal: passed
• exact reference waveform parity against clean 0.37.0: passed
• 10/60/180-second real model renders and WAV/recipe checksum validation: passed